// const path = require("path");
const Router = require("koa-router");
const swaggerJSDoc = require("swagger-jsdoc");
const { APP_PORT } = require("../config/config.default");
const swaggerApiDocs = require("../utils/swaggerApiDocs");

// 实例化子路由对象
const router = new Router();

/**
 * Swagger文档核心定义配置
 * 该配置遵循OpenAPI 3.0规范，用于描述API的整体信息和结构
 * 是生成Swagger文档的基础配置
 */
const swaggerDefinition = {
  /**
   * 指定OpenAPI规范版本
   * 3.0.0及以上版本支持securitySchemes等现代认证配置
   * 低于此版本可能导致认证功能无法正常工作
   */
  openapi: "3.0.0",
  /**
   * API文档的基本元信息
   * 这些信息会显示在Swagger UI的顶部区域
   */
  info: {
    title: "koa2-api项目接口", // 项目接口文档的标题
    version: "1.0.0", // 接口版本号，建议遵循语义化版本控制
    description: "koa2-api项目接口文档", // 对项目接口的简要描述
  },
  /**
   * API服务的主机地址
   * 格式为"域名:端口"，用于Swagger UI生成完整的请求URL
   * 注意：在OpenAPI 3.0中，此配置已被 servers 替代，仅作为兼容保留
   */
  // host: `localhost:${APP_PORT}`,
  /**
   * API服务的服务器配置（OpenAPI 3.0 推荐配置）
   * 用于定义API的基础访问地址，支持多环境配置
   * 根据 OpenAPI 3.0 官方文档，servers 字段的类型是 Server Object 的数组（即 [Server Object]），而每个 Server Object 必须包含 url 字段（字符串类型，代表服务器基础地址），还可可选包含 description（描述）、variables（路径变量）等属性。
   * 当 swagger-jsdoc 解析到 servers 是字符串时，会默认把它包装成 [{ url: "你的字符串值" }] 的数组格式
   */
  servers: [
    {
      url: `http://localhost:${APP_PORT}`, // 本地开发环境的API基础地址
      description: "本地开发服务器", // 对该环境的描述
    },
    // 可添加更多环境配置，如生产环境、测试环境
    // { url: "https://api.example.com", description: "生产环境" },
    // { url: "https://test-api.example.com", description: "测试环境" },
  ],
  /**
   * API的基础路径
   * 所有接口路径都会基于此路径进行拼接
   * 例如basePath为"/api"时，接口"/users"实际访问路径为"/api/users"
   * 注意：在OpenAPI 3.0中，此配置已被servers替代，仅作为兼容保留
   */
  basePath: "/",
  /**
   * 合并外部接口文档配置
   * 此处导入通过Apifox工具生成并导出的接口文档配置
   * 注意：如果导入的配置中存在与上述字段同名的属性，
   * 会覆盖当前定义的属性，需确保配置兼容性
   */
  ...swaggerApiDocs, // 使用本地的接口文档配置（通过 apifox 工具生成导出的）
};
/**
 * Swagger文档生成选项配置
 * 用于配置swagger-jsdoc的解析行为和文档来源
 */
const options = {
  /**
   * 错误处理配置
   * 解析出错是否抛出异常？默认 false
   * 设为true时，解析过程中遇到错误会抛出异常
   * 开发环境建议开启，便于及时发现配置问题；生产环境可关闭
   */
  failOnErrors: true,
  /**
   * 关联文档核心定义
   * 将前面定义的 swaggerDefinition 作为文档的基础配置
   */
  definition: swaggerDefinition,
  /**
   * 接口文档来源配置
   * 数组元素为包含@swagger注解的文件路径（支持通配符）
   * 本项目采用Apifox工具生成接口文档，直接整合到definition中，
   * 因此无需通过注解方式生成，故设为空数组
   */
  // apis: [path.join(__dirname, "./*.route.js")], // 写有@swagger注解的router存放地址, 最好借助path.join()来使用绝对路径
  apis: [], // 通过swagger注解的方式写接口文档太麻烦，太多注释还影响接口代码的阅读，推荐使用 apifox 工具生成接口文档直接放到 definition 里
};
/**
 * 生成Swagger规范文档对象
 * 通过swagger-jsdoc解析上述配置，生成符合OpenAPI规范的JSON结构
 * 该对象将用于Swagger UI展示和接口调试
 */
const swaggerSpec = swaggerJSDoc(options);

/**
 * 获取接口文档的数据源接口
 */
router.get("/swagger.json", (ctx) => {
  ctx.set("Content-Type", "application/json");
  // console.log("swaggerSpec", swaggerSpec);
  ctx.body = swaggerSpec;
});

module.exports = router;
